---
title: "Filter Component"
---

{% if isFramework("javascript", "angular", "vue") %}
Filter components allow you to add your own filter types to AG Grid. Use them when the Provided Filters do not meet your requirements.
{% /if %}

{% if isFramework("react") %}
{% videoSection id="98JVaTcoexc" title="React Custom Filter Components" showHeader=true %}
Filter components allow you to add your own filter types to AG Grid. Use them when the Provided Filters do not meet your requirements.
{% /videoSection %}
{% /if %}

The example below shows a custom filter on the `Athlete` column with "fuzzy" matching.

{% gridExampleRunner title="Custom Filter Component" name="custom-filter" /%}

## Implementing a Filter Component

To configure custom filters, first enable the grid option `enableFilterHandlers`.

{% note %}
If you do not enable the grid option `enableFilterHandlers`, it is still possible to use custom filters, however this will involve embedding your filter logic into the custom component, and is not recommended. See [Legacy Filter Component](./component-filter-legacy/).
{% /note %}

Implementing a custom filter requires two parts:
- The custom filter component which will be displayed to the user.
- The the logic to run the filter.

{% if isFramework("react") %}
Custom filter components are controlled components, which receive a filter model as part of the props, and pass model updates back to the grid via the `onModelChange` callback.
{%/if %}

{% if isFramework("javascript", "angular", "vue") %}
The custom filter component receives a filter model as part of the params (which is updated when the `refresh` method is called). When the model is changed via the UI, it should pass model updates back to the grid via the `onModelChange` callback.
{%/if %}

A filter model of `null` means that no filter is applied (the filter displays as inactive). Note that the filter is applied immediately when `onModelChange` is called. This behaviour can be changed by [Using Buttons](#using-buttons).

{% partial file="./_component-interface-javascript.mdoc" /%}
{% partial file="./_component-interface-angular.mdoc" /%}
{% partial file="./_component-interface-react.mdoc" /%}
{% partial file="./_component-interface-vue.mdoc" /%}


## Custom Filter Parameters

{% if isFramework("javascript") %}
The `init(params)` method takes a params object with the items listed below. If custom params are provided via the `colDef.filterParams` property, these
will be additionally added to the params object, overriding items of the same name if a name clash exists.
{% /if %}

{% if isFramework("angular") %}
The `agInit(params)` method takes a params object with the items listed below. If custom params are provided via the `colDef.filterParams` property, these
will be additionally added to the params object, overriding items of the same name if a name clash exists.
{% /if %}

{% if isFramework("vue") %}
When a Vue component is instantiated the grid will make the grid APIs, a number of utility methods as well as the cell and
row values available to you via `this.params` - the interface for this is documented below.

If custom params are provided via the `colDef.filterParams` property, these
will be additionally added to the params object, overriding items of the same name if a name clash exists.
{% /if %}

{% if isFramework("javascript", "angular", "vue") %}
{% interfaceDocumentation interfaceName="FilterDisplayParams" /%}
{% /if %}

{% if isFramework("react") %}
### Filter Props

The following props are passed to the custom filter components (`CustomFilterDisplayProps` interface). If custom props are provided via the `colDef.filterParams` property, these will be additionally added to the props object, overriding items of the same name if a name clash exists.
{% /if %}

{% if isFramework("react") %}
{% interfaceDocumentation interfaceName="CustomFilterDisplayProps" config={ "description": "" } /%}
{% /if %}

{% if isFramework("react") %}
### Filter Callbacks

The following callbacks can be passed to the `useGridFilterDisplay` hook (`CustomFilterDisplayCallbacks` interface). All the callbacks are optional. The hook only needs to be used if callbacks are provided.

{% /if %}

{% if isFramework("react") %}
{% interfaceDocumentation interfaceName="CustomFilterDisplayCallbacks" config={ "description": "" } /%}
{% /if %}

## Filter Logic

The logic to run the filter can be provided in one of two ways:
- As a `doesFilterPass` callback for simple filter cases.
- As a filter handler object for more complex filter cases.

The logic is passed via the `filter` property along with the custom component as a `ColumnFilter` object.

{% interfaceDocumentation interfaceName="ColumnFilter" config={ "description": "" } /%}

{% note %}
The filter logic is only used with the [Client-Side Row Model](./row-models/). If being used exclusively with other row models, it does not need to be provided as the filtering logic is performed on the server. If a handler is provided, it will still be instantiated, but `doesFilterPass` will not be called.
{% /note %}

### doesFilterPass Callback

```{% frameworkTransform=true %}
const gridOptions = {
    columnDefs: [
        {
            field: 'year',
            filter: {
                component: YearFilter, // custom filter component
                doesFilterPass: (params) => {
                    // evaluate filter for row here
                    return model === params.handlerParams.getValue(params.node);
                },
            },
        }
    ],
}
```

The callback `doesFilterPass(params)` will be called for each row when filtering is performed (and the filter is active), and takes the following as a parameter:

{% interfaceDocumentation interfaceName="DoesFilterPassParams" config={ "description": "" } /%}

### Filter Handler

```{% frameworkTransform=true %}
const gridOptions = {
    columnDefs: [
        {
            field: 'year',
            filter: {
                component: YearFilter, // custom filter component
                handler: (params) => ({
                    doesFilterPass: (params) => {
                        // evaluate filter for row here
                        return passes;
                    },
                    // other handler methods
                }),
            },
        }
    ],
}
```

The filter handler function should return a `FilterHandler` which will be created when the filter is active. The `doesFilterPass` method on the evaluator will be called for each row when filtering is performed (and the filter is active).

The filter handler is useful for when the filter model needs parsing to allow for fast comparison of values. The handler is passed the latest filter model via the `init` / `refresh` methods, which can then process the model before `doesFilterPass` is called.

{% interfaceDocumentation interfaceName="FilterHandler" config={ "description": "" } /%}

It is also possible to define filter handlers in the `filterHandlers` grid option, and then refer to them by the string key in the column definition.

{% apiDocumentation source="grid-options/properties.json" section="filter" names=["filterHandlers"] /%}

## Using Buttons

It is possible to use the [Filter Buttons](./filter-applying/) for grid-provided filters with custom filter components.

{% gridExampleRunner title="Filter Buttons" name="custom-filter-buttons" /%}

The example above demonstrates using filters with buttons via the same custom filter component:
- The **Year Default** column does not use buttons.
- The **Year Apply** column uses the apply button, and additionally closes the filter popup on apply.
- The **Year Reset** column uses the reset button, which will set the filter back to the default model and apply it.

The buttons are configured by passing additional parameters to the filter (interface `FilterWrapperParams`).

{% interfaceDocumentation interfaceName="FilterWrapperParams" names=["buttons", "closeOnApply"] config={ "description": "" } /%}

When the buttons are pressed, the custom filter `state` parameter will be updated via the `refresh(params)` method, with `state.model` being the model that should be displayed in the filter.

With the `Apply` button present, the filter component no longer needs to call `onModelChange(model)` as the grid will apply the model when the button is clicked (although it can still be called if the component wants to apply a model in some other way). Instead, the filter component will call `onStateChange({ model })` with the model that is currently displayed in the filter component. This is the model that the grid will apply when the button is clicked. If the filter is being used without buttons, it can also call `onAction('apply')` to apply the model set via the state.

## Associating Floating Filter

If you create your own filter you have two options to get floating filters working for that filter:

1. You can create your own [Custom Floating Filter](./component-floating-filter/).
1. You can implement the `getModelAsString()` method on your filter evaluator. If you implement this method and don't provide a custom floating filter, AG Grid will automatically provide a read-only version of a floating filter. See [Custom Filter And Read-Only Floating Filter](./component-floating-filter/#example-custom-filter-and-read-only-floating-filter).

If you don't provide either of these two options for your custom filter, the display area for the floating filter will be empty.

## Custom Filters Containing a Popup Element

Sometimes you will need to create custom components for your filters that also contain popup elements. This is the case for Date Filter as it pops up a Date Picker. If the library you use anchors the popup element outside of the parent filter, then when you click on it the grid will think you clicked outside of the filter and hence close the column menu.

There are two ways you can get fix this problem:

* Add a mouse click listener to your floating element and set it to `preventDefault()`. This way, the click event will not bubble up to the grid.
  This is the best solution, but you can only do this if you are writing the component yourself.
* Add the `ag-custom-component-popup` CSS class to your floating element. An example of this usage can be found here: [Custom Date Component](./filter-date/#custom-selection-component)

## Using Custom Filters with Grid-Provided Filter Logic

It is possible to use the grid-provided filter logic with custom filter components.

```{% frameworkTransform=true %}
const gridOptions = {
    columnDefs: [
        {
            field: 'year',
            filter: {
                component: YearFilter, // custom filter component
                handler: 'agNumberColumnFilterHandler', // grid-provided Number Filter handler
            },
        }
    ],
}
```

The grid-provided handlers are:
- `'agTextColumnFilterHandler'` - [Text Filter](./filter-text/) handler.
- `'agNumberColumnFilterHandler'` - [Number Filter](./filter-number/) handler.
- `'agDateColumnFilterHandler'` - [Date Filter](./filter-date/) handler.

The example below demonstrates using the Number Filter handler with a custom filter component:

{% gridExampleRunner title="Use Grid Handlers" name="use-grid-handlers" /%}

## Accessing the Component Instance

{% if isFramework("angular", "vue", "javascript") %}
AG Grid allows you to get a reference to the filter component instances via the `api.getColumnFilterInstance(colKey)` method.
{% /if %}

{% if isFramework("react") %}
AG Grid allows you to get a reference to the filter component instances via `api.getColumnFilterInstance(colKey)`. This returns a wrapper component that matches the provided grid filter components that implement `FilterDisplay`. To get the React custom filter component, the helper function `getInstance` can be used with this. As React components are created asynchronously, it is necessary to use a callback for both methods.
{% /if %}

Similarly, you can get a reference to the filter handler via `api.getColumnFilterHandler(colKey)`.

{% if isFramework("angular") %}
```ts
// let's assume an Angular component as follows
@Component({
    selector: 'filter-cell',
    template: `
        Filter: <input style="height: 10px" #input (ngModelChange)="onChange($event)" [ngModel]="text">
    `
})
class PartialMatchFilterComponent implements IFilterDisplayAngularComp {
    ... // standard filter methods hidden

    // put a custom method on the filter
    myMethod() {
        // does something
    }
}

// later in your app, if you want to execute myMethod()...
laterOnInYourApplicationSomewhere() {
    // assume filter on name column
    api.getColumnFilterInstance<PartialMatchFilterComponent>('name').then(angularFilterInstance => {
        angularFilterInstance.myMethod();
    });
}
```
{% /if %}

{% if isFramework("react") %}
```ts
// let's assume a React component as follows
export default forwardRef((props, ref) => {
    useImperativeHandle(ref, () => {
        return {
            ... // required filter methods

            // put a custom method on the filter
            myMethod() {
                // does something
            }
        }
    });

    ... // rest of component
}

// later in your app, if you want to execute myMethod()...
laterOnInYourApplicationSomewhere() {
    // get reference to the AG Grid Filter component on name column
    api.getColumnFilterInstance('name').then(filterInstance => {
        getInstance(filterInstance, comp => {
            if (comp != null) {
                comp.myMethod();
            }
        });
    });
}
```
{% /if %}

{% if isFramework("vue") %}
```ts
// let's assume a VueJS component as follows
export default {
    template: `<input style="height: 20px" :ref="'input'" v-model="text">`,
    data() {
        ...data
    },
    methods: {
        myMethod() {
            // does something
        },
        ...other methods
    },

    // later in your app, if you want to execute myMethod()...
    laterOnInYourApplicationSomewhere() {
        // assume filter on name column
        api.getColumnFilterInstance('name').then(filterInstance => {
            filterInstance.myMethod();
        });
    }
```
{% /if %}

The example below illustrates how a custom filter component can be accessed and methods on it invoked. If you click on the `Invoke Filter Instance Method` button, it will invoke the instance `componentMethod`, which logs to the developer console.

{% gridExampleRunner title="Filter Component Instance" name="filter-component"  exampleHeight=445 /%}


## Next Up

Continue to the next section to learn about [Floating Filters](./floating-filters/).
